﻿
# ADFS and Azure AD OAuth for HPRM ServiceAPI

## Purpose
This is a sample extension for the ServiceAPI to support active authentication when ADFS or Azure Active Directory (AAD) is being used as the authentication layer.


## Background
When a 3rd party identity provider (IdP), such as AAD or ADFS, is used as the authentication layer then there are two possible ways we might want to connect:
1. Passive - this is when a web browser authenticates to the service (or Web Client) and is redirected to the IdP for authentication and then directed back upon successful authentication
2. Active - is when a non browser consumer (such as a Windows application) authenticates to the web service.

The ServiceAPI help file documents the implementation of passive authentication for the web client (or web drawer).  If you want to allow active authentication (for non web based access) to the ServiceAPI then this sample may assist.


## Standards
AAD and ADFS support OAuth 2.0 for active authentication, from Wikipedia: 
OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

## Supporting Technology
The open source framework OWIN provides the assemblies required to inject OAuth into the ServiceAPI pipeline.


## What does this sample do?
This sample does not do much, it simply uses the OWIN framework to inject the Owin AAD OAuth2 'Bearer' authentication module into the ServiceAPI HTTP pipeline.  This means that if any client sends a bearer token as an HTTP header it will be recognized by the ServiceAPI.


## Installing this Sample
To install this sample:
1. build this project
2. copy all the DLLS from the output folder to the ServiceAPI bin folder
3. configure the web.config as described below.


## Configuring Web.config
### Azure AD
The following entries must be added to the appSettings of the web.config.  The tenant is the name of your Active Directory instance in AAD, within the directory you must create a Web Application for the ServiceAPI, the Audience is the APP ID URI and the Client Id is the Client ID.

```
<add key="ida:Tenant" value="hprmdevtest.onmicrosoft.com" />
<add key="ida:Audience" value="https://811.hprm.info/ServiceAPI/" />
<add key="ida:ClientID" value="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />```

### ADFS
The following entries are required in the web.config appSettings for ADFS. Of course change the server names for your ADFS and web server names.
```
<add key="ida:AdfsMetadataEndpoint" value="https://adfs1.testteam.local/FederationMetadata/2007-06/FederationMetadata.xml" />
<add key="ida:Audience" value="https://davidc2012.trim.lab/HPRMServiceAPI/" />```

### Anonymous access
Add the below to the system.Web section to prevent anonymous access.  Also open IIS manager and enable anonymous access while disabling all other authentication methods.
```
<authorization>
   <deny users="?" />
</authorization>
<authentication mode="None" />
```
	
## Creating the Application in AAD
This document assumes you are already using AAD so does not deal with setting up the directory.  To create the application within the directory:
1) open the directory in AAD
2) go to Applications
3) Add
4) Select 'Add an application my organization is developing'
5) enter a meaningful and unique name (e.g. HPRM ServiceAPI)
6) Next
7) enter an App ID ((e.g. https://<MyDomain>/HPRMServiceAPI/))
8) enter the web service URL as the Sign-On URL
9) OK.


## Giving permission for OAuth Access
For the application created in the previous step to be useful for OAuth connection it must be possible to create Azure AD client applications that have permissions to this application.  To do this we must edit the manifest of the application created in the previous step.  This is done by:
1) opening the application
2) selecting the 'Manage Manifest' button
3) downloading the manifest file
4) there should be an empty property called oauth2Permissions (e.g. "oauth2Permissions":[])
5) modify this to look something like the below,
6) use the guidGen utility to generate a new guid for the id property
7) save and re-upload the manifest.

This is described in more details here: http://msdn.microsoft.com/en-us/library/dn132599.aspx#BKMK_Updating


## Example OAuth Permissions

"oauth2Permissions": [
    {
      "adminConsentDescription": "Allow the application full access to the HPRM ServiceAPI on behalf of the signed-in user",
      "adminConsentDisplayName": "Have full access to the HPRM ServiceAPI",
      "id": "A220008F-E82F-40F6-B92E-CA57F832F3AB",
      "isEnabled": true,
      "origin": "Application",
      "type": "User",
      "userConsentDescription": "Allow the application full access to the HPRM ServiceAPI on your behalf",
      "userConsentDisplayName": "Have full access to the HPRM ServiceAPI",
      "value": "user_impersonation"
    }
  ],


## What Next? ***
Next you need an application that is able to use a bearer token to talk to the web service, use the ADAL library to build one of these.